using System.Text.Json.Serialization;

namespace Sage.CloudStorage.Qiniu.Models
{
    /// <summary>
    /// 完成分片上传时的分片信息类
    /// 用于完成整个分片上传任务时提交已上传分片的清单
    /// </summary>
    /// <remarks>
    /// **完成上传流程**：
    /// 1. 收集所有已成功上传的分片信息
    /// 2. 构建CompletePartInfo列表，包含分片号和ETag
    /// 3. 提交给七牛云进行文件合并
    /// 4. 七牛云验证所有分片并生成最终文件
    /// 
    /// **数据要求**：
    /// - 分片号必须连续且从1开始
    /// - ETag必须与实际上传时返回的值完全一致
    /// - 列表必须按分片号升序排列
    /// - 所有分片都必须成功上传
    /// 
    /// **验证机制**：
    /// - 七牛云会验证每个分片的ETag有效性
    /// - 确保分片数据完整性和一致性
    /// - 验证失败会拒绝完成上传请求
    /// </remarks>
    public class CompletePartInfo
    {
        /// <summary>
        /// 分片号，标识分片在文件中的位置
        /// 从1开始的连续整数，最大值为10000
        /// </summary>
        /// <remarks>
        /// **分片号规则**：
        /// - **起始值**：必须从1开始，不能从0开始
        /// - **连续性**：分片号必须连续，不能跳号
        /// - **范围限制**：取值范围1-10000，超出范围会被拒绝
        /// - **顺序要求**：在完成上传时必须按升序排列
        /// 
        /// **业务含义**：
        /// - 决定分片在最终文件中的位置
        /// - 分片号1对应文件的开始部分
        /// - 分片号越大，对应文件越靠后的部分
        /// - 最后一个分片号对应文件的结尾部分
        /// 
        /// **使用示例**：
        /// ```csharp
        /// var parts = new List&lt;CompletePartInfo&gt;
        /// {
        ///     new() { PartNumber = 1, Etag = "etag_of_part_1" },
        ///     new() { PartNumber = 2, Etag = "etag_of_part_2" },
        ///     new() { PartNumber = 3, Etag = "etag_of_part_3" }
        /// };
        /// ```
        /// 
        /// **注意事项**：
        /// - 分片号必须与上传时使用的分片号完全一致
        /// - 缺少任何一个分片都会导致完成上传失败
        /// - 分片号重复会被视为错误
        /// - 建议在上传过程中维护分片号和ETag的对应关系
        /// </remarks>
        [JsonPropertyName("partNumber")]
        public int PartNumber { get; set; }

        /// <summary>
        /// 分片的ETag值，由分片上传时服务器返回
        /// 用于验证分片数据的完整性和正确性
        /// </summary>
        /// <remarks>
        /// **ETag验证**：
        /// - 必须与UploadPartResponse中返回的Etag完全一致
        /// - 七牛云会验证每个ETag的有效性
        /// - ETag不匹配会导致完成上传失败
        /// - 区分大小写，必须精确匹配
        /// 
        /// **安全保障**：
        /// - 确保分片在上传过程中未被篡改
        /// - 验证分片数据的完整性
        /// - 防止恶意或错误的分片数据
        /// - 提供端到端的数据完整性保证
        /// 
        /// **数据来源**：
        /// - 从UploadPartResponse.Etag字段获取
        /// - 在分片上传成功后立即保存
        /// - 建议持久化存储以支持断点续传
        /// - 用于构建完成上传请求
        /// 
        /// **格式要求**：
        /// - 通常为28个字符的Base64编码字符串
        /// - 不能为空或null
        /// - 不能包含非法字符
        /// - 必须是七牛云服务器生成的有效ETag
        /// 
        /// **使用流程**：
        /// ```csharp
        /// // 1. 上传分片时保存ETag
        /// var uploadResponse = await UploadPartAsync(...);
        /// var partInfo = new CompletePartInfo 
        /// {
        ///     PartNumber = partNumber,
        ///     Etag = uploadResponse.Etag  // 保存服务器返回的ETag
        /// };
        /// 
        /// // 2. 完成上传时提交
        /// var completeRequest = new CompleteMultipartUploadRequest
        /// {
        ///     Parts = allParts.OrderBy(p => p.PartNumber).ToList()
        /// };
        /// ```
        /// </remarks>
        [JsonPropertyName("etag")]
        public string Etag { get; set; } = "";
    }
}
